Windows (Microsoft) System

Device Nominations (C/C++)

Nomination Routine

Description of device

gMwin(hInst,hPrevInst)

Opens a default window

gMwinw(hInst,hPrevInst,x,y,width,height)

Opens a window at the specified position and size

gMwinao(hInst,hPrevInst,hWnd,hDC)

Opens GINO using an existing bitmap

gMwindc(hInst,hPrevInst,hWnd,hDC)

Opens GINO using a private bitmap

gMwinp (hInst,hPrevInst)

Opens a Windows printer for GINO output

gMwindp (hInst,hPrevInst)

Opens the default Windows printer for GINO output

status=gMwinpp(hInst, hPrevInst ,mode, devname, dlen, filename, flen, n, prop)

Printing and Setup control for Windows printers

gGuiwin()

Window API graphics in GINOMENU

Device Nominations (F90/Delphi/VB/.NET)

Nomination Routine

Description of device

gMwin

Opens a default window

gMwinw(x,y,width,height)

Opens a window at the specified position and size

gMwinao(hWnd,hDC)

Opens GINO using an existing bitmap

gMwindc(hWnd,hDC)

Opens GINO using a private bitmap

gMwinp

Opens a Windows printer for GINO output

gMwindp

Opens the default Windows printer for GINO output

status=gMwinpp(mode,devname,filename,n,prop)

Printing and Setup control for Windows printers

gGuiwin

Window API graphics in GINOMENU

Device Characteristics

Default Width (of max)

3/4

variable

Maximum

variable

Default Height (of max)

3/4

variable

Maximum

variable

Image Handling (output, input, copy)

Yes

Printer Dependent

Yes⁴

Cursor Types*

Yes¹

Cursor Actions*

Yes²

Event Types*

Yes³

Batch Updates*

Yes

Auxiliary Drawing Areas (up to 250 pairs)

Yes

Window/Device Titling

Yes

Devices A to H

Maximum Width

Variable

Maximum Height

Variable

Colours / Pens

Screen / printer dependent

Colour Palette

<=256 colours = Dynamic, >256 = Direct

Broken Linestyles

Drawing Modes

GDEFAULT, GERASER, GNOT, GAND, GOR, GXOR and 11-19 hardware specific

Thick Lines

Yes

Line Ends

Arcs

Symbols

Fonts

As installed including 6 registered (100,101,102,150,151,170)

Character Sizes

Any size (16 pseudo sizes)

Character Angles

Any angle

Italic Characters

Yes

Polygonal Filling

Multi-polygon, solid fill, 1024 vertices

Segments

Clipping

Yes (Windowing only)

Transform/Viewing

Shading

Lights

Texture Mapping

Mouse Positioning

Yes

*         when using the gMwinao() nomination routine, the handle to the window must be provided for these features to be available
Yes¹    GDEFAULT, GSMALLCROSS, GMEDIUMCROSS, GLARGECROSS, GCROSSHAIR, GX, GLARGEX, GPOINTER, GHOURGLASS, GEXIT (Colour control only on GLARGECROSS/GCROSSHAIR)
Yes²    GPOLYLINE, GRUBBERBAND GRUBBERBOX, GRUBBERSQUARE, GRUBBERELLIPSE, GRUBBERCIRCLE
Yes³    GKEYPRESS, GLOCATOR, GMOVEMENT, GKEYRELEASE, GRESIZE, GMOUSEWHEEL
Yes⁴    Input and copying is only available when the device is operating in direct colour mode (see gSetColourInfo())

Driver Availability

The Mwin series of drivers are used for API graphics output to the screen or printer under Windows. For OpenGL graphics under Windows, see gWogl.

Device Nomination & Usage

When using the C routines, all except gGuiwin() require the handle to the current instance of the program (hInst) and, if available, the handle to the previous instance (hPrevInst) to be passed to the nomination routine as the first two parameters. In a C program these parameters are available in the WinMain() procedure. The nomination routines are described below:

gMwin

This nomination routine opens a standard window of 3/4 screen size at a default position. The device driver will update the window after every five hundred calls, upon a gFlushGraphics() / gCloseDevice() / gSuspendDevice(), before cursor or event routines are called, or upon a Windows paint event. The following examples show the nomination routine in the context of a program:

[C/C++]
#include <windows.h>
#include <gino-c.h>
int PASCAL WinMain(HANDLE hInst, HANDLE hPrevInst,
LPSTR lpszCmdParam, int nCmdShow)
{

/* Nominate the device */
gMwin(hInst, hPrevInst);

/* Use GINO routines here */

/* Close the device */
gCloseDevice();
}

[F90]
Program Main
use gino_f90

! Nominate the device
call gMwin

! use GINO routines here

.

! Close the device
call gCloseDevice
Stop
End

gMwinw

gMwinw() is essentially the same as gMwin(), however the size & position of the window can be specified. x, y is the pixel position of the top left corner of the window (coordinate (0, 0) is the top left of the screen) and width, height are the width and the height of the required window in pixels. If width or height are less than or equal to zero the default size is used. If the requested size is larger than the screen then the size is automatically set to the same size as the screen.

gMwinao

This nomination routine is most useful when using this driver in a Windows programming environment, allowing for greater flexibility, but at the loss of some ease of use. Output can be directed to existing windows and/or device contexts using Windows handles passed to this routine by argument. (See GUI Programming).

gMwindc

The gMwindc() nomination routine is similar to gMwinao() except that GINO creates and maintains an internal private bit map of the same size as the bitmap who's handle is passed in hDC. This is most useful in environments where a new bitmap handle is continually generated for the drawing area when a resize or repaint message is generated such as .NET and Delphi . The advantage of creating a private bitmap is that any drawing previously directed to the drawing area is not lost and does not have to be regenerated as well. Details of how to use this nomination routine and its associated utility routines are found in the section on GUI programming (see GUI Programming).

gMwinp

This nomination routine will use a windows printer for output. A dialog box will be displayed upon nomination allowing the user to select a printer. The form of a call to this routine is the same as a call to gMwin().

gMwindp

This nomination routine will use the default windows printer for output. The form of a call to this routine is the same a call to gMwin() or gMwinp().

Print Status Detection

A function gMwinst() is provided with this driver to detect the status of a print job, used in conjunction with either gMwinp() or gMwindp(). gMwinst() can return the following values:

0	Print job OK

1	Print job cancelled

2	Could not find a default print device

3	Job cancelled while printing

status=gMwinpp(mode,devname,dlen,filename,flen,n,prop)

This nomination provides comprehensive control over the printer setup and printing of GINO output through the Windows printer interface. The additional arguments are:

mode

-2	Return current printer properties (returns status > 0)

-1	Restore default printer properties and return them (returns status > 0)

0	Open Printer Setup Window (returns status > 0)

1	Restore default printer properties and print (same as gMwindp())

2	Open Printer Dialogue and print (same as gMwinp())

3	Print using current/default printer

devname
Printer Device Name (input/output)

dlen
Length of devname (C/C++ only)

filename
Printer Output File name (in place of device) : used when PrinttoFile property = 1 in modes 2 and 3. If filename is blank when the PrinttoFile property is set, a file of the name <application>.prn is generated.

flen
Length of filename (C/C++ only)

n
Number of elements in prop array (rounded down to nearest even number)

prop
Integer array of pairs of <property> and <setting> (see table below). The setting values are used to change the current printer properties in modes 0, 2 and 3 but will be returned in all modes. Thus if prop contains the values: 7,2,1,2 the printer properties will be changed to landscape orientation and print 2 copies. If mode = -2 and prop contains the values: 2,0,8,0 the (device name,) paper size and print quality of the current printer will be returned. If prop[0]<=0 the first n/2 of the property flags and their values are returned.

Property

Property Description

Settings

No. of copies

Number of copies

Paper size
(see Windows wingdi.h)

= 1,     Letter
= 5,     Legal
= 9,     A4
= 256, User defined

Paper length

Length in tenths of mm

Paper width

Width in tenths of mm

Paper Source
(see Windows wingdi.h)

= 1, Default (Upper)
= 2, Lower
= 4, Manual
= 5, Envelope

Scale Factor

Scale/100 (ie 50 = half size)

Orientation

= 1, Portrait
= 2, Landscape

DPI/Quality

> 0, DPI
= -1, Draft
= -2, Low
= -3, Medium
= -4, High Quality

Colour

= 1, Monochrome
= 2, Colour

Duplex

= 1, Simple
= 2, Duplex
= 3, Vertical

TTopt

= 1, Bitmap
= 2, Download (HP printers)
= 3, Substitute (PostScript printers)

PrinttoFile

= -2, Disable and hide Print to File toggle
= -1, Disable Print to File toggle
= 0, Leave toggle as is (default)
= 1, Select toggle and use filename

status

0	Printing in progress

1	Print Cancelled or not required

2	No default/current printer available

Return Status - If status > 0 the application should immediately call gCloseDevice() and re-nominate another GINO device (eg. gMwin() or gMwinw()).

gGuiwin

This nomination routine is only used in GINOMENU applications, where graphics frames are required to display GINO graphics in a Windows environment. Further details are found in the GINOMENU User Guide.

Window Size

If the gMwin() or gMwinw() routines have been used to nominate the device any changes the user of the application makes to the window size during operation will be handled by the driver. The driver will ensure that the picture is updated by redrawing from the backing store and scroll bars added to the window, if needed. However GINO is not able to take any further action until after gNewDrawing() is called. At this point the driver will resize the drawing limits to fit the window and these can be enquired by the application using the routine gEnqDrawingLimits() if the user wishes to re-scale the picture.

If the window size is changed by the user, this takes priority over the programmers request for a change through gSetDrawingLimits().

Window Title

The default window title of a GINO application is a string composed of the GINO version and license owner. This can be superceded in the following order of precedence:

1) GINO config variable MWINTITLE

2) System environment variable MWINTITLE

3) Application call to gSetDeviceTitle()

Colour Palette

When running a GINO application in one of the Windows 8bit (256) colour modes, the driver will, by default, create and use a dynamic colour palette (ndt=3) and the number of colours is set to the number of palette entries that Windows reports as being available. In this mode, an exact colour match may not always be possible as Windows will use the nearest match when no more palette entries are available. There may also be some re-painting problems when other high-colour applications are running (see below).

When running in one of the 16bit, 24bit or 32bit colour modes (>256 colours), the driver will operate in direct mode (ndt=4), but an internal GINO palette with 1024 entries is still available. In this mode, gDefineRGB() can still be used but will have no effect on graphics already drawn.

An application may alter this default situation by using the routine gSetColourInfo() to either reduce the number of palette entries (in dynamic colour mode) or change to another colour mode which may give better results when running with other applications. The routine gSetColourInfo() may also be used to increase the number of colours with printing devices where Windows reports that there is only one colour available but the printer is capable of producing greyscales.

In all modes, changes to colour 0 (GBACKGROUND) may not be seen unless followed by a call to gNewDrawing().

Drawing Modes

In addition to the GINO drawing modes 6-10, this driver implements a further nine pen types:

11	The pen is always black [Output = Black]

12	The pen is always white [Output = White]

13	The inverse of the GINO AND pen [Output = ~(Pen & Screen)]

14	The inverse of the pen colour [Output = ~Pen]

15	The combination of colours common to the pen and the inverse of the screen[Output = (~Screen) & Pen]

16	A combination of the screen and the inverse of the pen [Output = (~Pen) \| Screen]

17	The inverse of the GINO OR pen [Output = ~(Pen \| Screen)]

18	A combination of the pen & the inverse of the screen [Output = (~Screen) \| Pen]

19	The inverse of the GINO XOR pen [Output = ~(Pen ^ Screen) ]

Note that the effect of the different drawing modes varies according to the Windows screen mode that the application is operating. When the device is in indexed mode (ie. 256 colours), the resulting colour is determined from the bit operation on the colour indices of the pen and the screen, whereas when Windows is operating in Direct (True) colour mode (16bit, 24bit etc), the resulting colour is determined by the bit operation on the RGB values of the pen and screen.

Thick Lines and Line Ends

The MWIN driver has been written to generate thick lines of all types, but the only true thick lines available through the GDI are those with round ends. Thus the no-ends and square-end types are generated by constructing a polygon of the required shape. To force the use of GDI thicklines use gSetLineEnd(GROUND).

Fonts/Character Sets

The default font used by the MWIN driver is a fixed pitch, modern font using the system default character set which normally maps to ANSI Courier. Any of the Windows installed fonts may be selected using the routine gSetCharFontName(), with the available list obtained through the routine gEnqFontNameList(). In addition, the following list of registered fonts are available through the routine gSetCharFont() :

Font Number

Font Name

0 or 100

Courier (fixed-pitch)

101

Swiss

102

Roman

150

Arial

151	Times New Roman

170

Symbol

Alternative character/language sets may be selected using the routine gSetCharSet(). This usually only affects character codes > 128 as character codes 32-127 will always contain the ANSI character set.

Input Focus in Graphics Cursor Mode

When gGetCursorEvent() is called, the input focus of the device is set to be the graphics window. When the key has been pressed, the focus is returned to the previous window before gGetCursorEvent() was called. This operation is not supported when using the gMwinao() nomination routine.

Events

The following event types can be set through the routine gAddEventType( intype): where intype can be one of the following:

GKEYPRESS

Key or Mouse button press

GLOCATOR

Screen position and Key/Mouse button press

GMOVEMENT

Pointer/Mouse movement

GKEYRELEASE

Key or Mouse button release

GRESIZE

Window resize

GMOUSEWHEEL

Mouse wheel movement

Multiple event types may be set concurrently. When the device has been nominated by gMwin() or gMwinw(), events are requested with the routine gWaitForEvent() with the resulting data for the event being returned through the routine gGetEventRecord() (see Advanced Interaction).

Information concerning events in conjunction with the gMwinao() nomination routine are described in the GUI programming environment section (see GUI Programming). Events are only supported if using the gMwinao() nomination routine with a window handle.

Cursor Types

All cursor types are windows resource cursors except GLARGECROSS which is a full window cross-hair cursor drawn in XOR mode. It uses the bakcol argument from gSetCursorType() to draw the cursor, so in order to operate correctly this value should not be set to 0. (See GUI programming with Cursor Types for an example).

Device Termination

When using either gMwin() or gMwinw(), the action at device termination is to halt GINO graphics and close the graphics window if gCloseDevice() has been called. If gSuspendDevice() has been called, the graphics window will remain on the screen and the program will pause at the call to gCloseGino(). The dialogue window will be closed at the same time as GINO is closed.

When using gMwinao(), at device termination it is the application programmers responsibility to release the bitmap device context.

Error Handling

When a GINO or other GINO library generates an error or warning message an error window is created and displayed at the bottom left of the screen. All subsequent error/warning messages are printed in this window. The user can alter the initial state of this window through the configuration variable NFERTR set in the configuration file GINO.CON as follows:

NFERTR

= 0	Visible(Default)

= 1

Iconized

= 2

Hidden

> 2	Errors are sent to a file "APPLICATION".ERR

Window Visibility

The current graphics and dialogue windows can be made visible/invisible using the routines gSetGraphicsVis() and gSetDialogueVis():

gSetGraphicsVis(gravis)

Make graphics window visible/invisible

gSetDialogueVis(diavis)

Make dialogue window visible/invisible

where gravis & diavis can be either GINVISIBLE or GVISIBLE to hide or show the window.

The routine gSetGraphicsVis() will have no effect when the device has been nominated by using the gMwinao() routine. Calls to gSetDialogueVis() apply in all cases.

Application Icon

The GINO icon will be assigned to all windows created through these nomination routines. An application can replace this with one of their choosing by adding an icon resource of the name "GinoIcon" to their application. A typical resource file should contain the line:

GinoIcon ICON myapp.ico

where myapp.ico is the name of the user supplied application icon file.

Interacting with other Windows Applications

GINO graphics sent to the screen can be copied onto the Windows clipboard by pressing <ALT> <PRINT SCREEN>. Transfer of graphics to other applications via OLE or DDE is not supported.

Error Messages

The WINDOWS driver may at one time or another popup a message box. These messages are mainly informational, but may effect the drivers behaviour. The messages are described below:

UNABLE TO CREATE A PALETTE. SOME COLOURS MAY LOOK WRONG.

When Windows memory or resources are low the WINDOWS driver will not be able to create an internal palette of colours. The program will still function, however the colours may not match the ones defined. Resolve this problem by closing one or more applications & restarting the GINO application. If the problem still persists, try restarting windows.

UNABLE TO CREATE THE MESSAGE WINDOW

Sometimes when an application has been improperly closed the dialogue window will still exist in memory, although the dialogue window may not be visible. The WINDOWS driver will not be able to use this instance or create a new instance, hence there will not be a dialogue window. Reasons for this can be programs crashing or being terminated part way through (i.e. by a debugger). The only solution to this problem is to restart windows.